package com.ar4j.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Defines a method in an ActiveRecord bean as one that runs a named native query. 
 */
@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface NamedQueryMethod {

  /**
   * @return the name of the SQL query to run, the record's context must have a 
   * named query source when the method is executed
   */
  String queryName();
  
  /**
   * <code> 
   *   {@literal @}NamedQueryMehod(queryName = "myQuery", bindVariables = { "prop1", "prop2" })<br/>
   *   public SomeBean findByNamedQuery(String value1, String value2)<br/>
   * </code><br/>
   * 
   * In the above example a query with the name "myQuery" is loaded via the bean's named query source (found in the context)
   * and executed with a set of parameters name value pairs where prop1 is set to value1 and prop2 is set to value2.
   * 
   * @return the names of any binding variables in the query, in the order their values appear in the parameter
   * list of the method definition
   */
  String[] bindVariables() default { };

  /**
   * @return true if the native SQL method is an update (INSERT/UPDATE/DELETE) 
   * as opposed to a lookup (SELECT)
   */
  boolean update() default false;
  
}
